<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.4"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Flow-IPC: ipc::transport::Native_handle_receiver Class Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Flow-IPC<span id="projectnumber">&#160;1.0.2</span>
   </div>
   <div id="projectbrief">Flow-IPC project: Full implementation reference.</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.4 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="namespaceipc.html">ipc</a></li><li class="navelem"><a class="el" href="namespaceipc_1_1transport.html">transport</a></li><li class="navelem"><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html">Native_handle_receiver</a></li>  </ul>
</div>
</div><!-- top -->
<div class="header">
  <div class="summary">
<a href="#pub-methods">Public Member Functions</a> &#124;
<a href="#pub-static-attribs">Static Public Attributes</a> &#124;
<a href="classipc_1_1transport_1_1Native__handle__receiver-members.html">List of all members</a>  </div>
  <div class="headertitle"><div class="title">ipc::transport::Native_handle_receiver Class Reference</div></div>
</div><!--header-->
<div class="contents">

<p>A documentation-only <em>concept</em> defining the behavior of an object capable of reliably/in-order <em>receiving</em> of discrete messages, each containing a native handle, a binary blob, or both.  
 <a href="classipc_1_1transport_1_1Native__handle__receiver.html#details">More...</a></p>

<p><code>#include &lt;<a class="el" href="native__handle__transport_8hpp_source.html">native_handle_transport.hpp</a>&gt;</code></p>
<div class="dynheader">
Collaboration diagram for ipc::transport::Native_handle_receiver:</div>
<div class="dyncontent">
<div class="center"><iframe scrolling="no" frameborder="0" src="classipc_1_1transport_1_1Native__handle__receiver__coll__graph.svg" width="534" height="384"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe>
</div>
<center><span class="legend">[<a href="graph_legend.html">legend</a>]</span></center></div>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-methods" name="pub-methods"></a>
Public Member Functions</h2></td></tr>
<tr class="memitem:a748df49e5098e922c5974643d7a1bbde"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a748df49e5098e922c5974643d7a1bbde">Native_handle_receiver</a> ()</td></tr>
<tr class="memdesc:a748df49e5098e922c5974643d7a1bbde"><td class="mdescLeft">&#160;</td><td class="mdescRight">Default ctor: Creates a peer object in NULL (neither connected nor connecting) state.  <a href="classipc_1_1transport_1_1Native__handle__receiver.html#a748df49e5098e922c5974643d7a1bbde">More...</a><br /></td></tr>
<tr class="separator:a748df49e5098e922c5974643d7a1bbde"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:accd891967ffb57341a26ed0764012713"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#accd891967ffb57341a26ed0764012713">Native_handle_receiver</a> (<a class="el" href="classipc_1_1transport_1_1sync__io_1_1Native__handle__receiver.html">sync_io::Native_handle_receiver</a> &amp;&amp;sync_io_core_in_peer_state_moved)</td></tr>
<tr class="memdesc:accd891967ffb57341a26ed0764012713"><td class="mdescLeft">&#160;</td><td class="mdescRight"><code><a class="el" href="namespaceipc_1_1transport_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.">sync_io</a></code>-core-adopting ctor: Creates a peer object in PEER state by subsuming a <code><a class="el" href="namespaceipc_1_1transport_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.">sync_io</a></code> core in that state.  <a href="classipc_1_1transport_1_1Native__handle__receiver.html#accd891967ffb57341a26ed0764012713">More...</a><br /></td></tr>
<tr class="separator:accd891967ffb57341a26ed0764012713"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a01de65ed1a7c747e5569e14221b6f9bf"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a01de65ed1a7c747e5569e14221b6f9bf">Native_handle_receiver</a> (<a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html">Native_handle_receiver</a> &amp;&amp;src)</td></tr>
<tr class="memdesc:a01de65ed1a7c747e5569e14221b6f9bf"><td class="mdescLeft">&#160;</td><td class="mdescRight">Move-constructs from <code>src</code>; <code>src</code> becomes as-if default-cted (therefore in NULL state).  <a href="classipc_1_1transport_1_1Native__handle__receiver.html#a01de65ed1a7c747e5569e14221b6f9bf">More...</a><br /></td></tr>
<tr class="separator:a01de65ed1a7c747e5569e14221b6f9bf"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:afa535558f8e9157d9e95e143376bb6e3"><td class="memItemLeft" align="right" valign="top"><a id="afa535558f8e9157d9e95e143376bb6e3" name="afa535558f8e9157d9e95e143376bb6e3"></a>
&#160;</td><td class="memItemRight" valign="bottom"><b>Native_handle_receiver</b> (const <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html">Native_handle_receiver</a> &amp;)=delete</td></tr>
<tr class="memdesc:afa535558f8e9157d9e95e143376bb6e3"><td class="mdescLeft">&#160;</td><td class="mdescRight">Disallow copying. <br /></td></tr>
<tr class="separator:afa535558f8e9157d9e95e143376bb6e3"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ae6d2627aa6ee2216cddbc801a28fa268"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae6d2627aa6ee2216cddbc801a28fa268">~Native_handle_receiver</a> ()</td></tr>
<tr class="memdesc:ae6d2627aa6ee2216cddbc801a28fa268"><td class="mdescLeft">&#160;</td><td class="mdescRight">Destroys this peer endpoint which will end the conceptual incoming-direction pipe (in PEER state, and if it's still active) and cancels any pending completion handlers by invoking them ASAP with <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297afe29343445a7bf167cc186a44bd2c6ed" title="Async completion handler is being called prematurely, because underlying object is shutting down,...">error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER</a>.  <a href="classipc_1_1transport_1_1Native__handle__receiver.html#ae6d2627aa6ee2216cddbc801a28fa268">More...</a><br /></td></tr>
<tr class="separator:ae6d2627aa6ee2216cddbc801a28fa268"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a78fbe1f543021b7b5d2ec1be70b83660"><td class="memItemLeft" align="right" valign="top"><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html">Native_handle_receiver</a> &amp;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a78fbe1f543021b7b5d2ec1be70b83660">operator=</a> (<a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html">Native_handle_receiver</a> &amp;&amp;src)</td></tr>
<tr class="memdesc:a78fbe1f543021b7b5d2ec1be70b83660"><td class="mdescLeft">&#160;</td><td class="mdescRight">Move-assigns from <code>src</code>; <code>*this</code> acts as if destructed; <code>src</code> becomes as-if default-cted (therefore in NULL state).  <a href="classipc_1_1transport_1_1Native__handle__receiver.html#a78fbe1f543021b7b5d2ec1be70b83660">More...</a><br /></td></tr>
<tr class="separator:a78fbe1f543021b7b5d2ec1be70b83660"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a2a3c7bb6843b8e1c2cabc9ce5ea2f709"><td class="memItemLeft" align="right" valign="top"><a id="a2a3c7bb6843b8e1c2cabc9ce5ea2f709" name="a2a3c7bb6843b8e1c2cabc9ce5ea2f709"></a>
<a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html">Native_handle_receiver</a> &amp;&#160;</td><td class="memItemRight" valign="bottom"><b>operator=</b> (const <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html">Native_handle_receiver</a> &amp;)=delete</td></tr>
<tr class="memdesc:a2a3c7bb6843b8e1c2cabc9ce5ea2f709"><td class="mdescLeft">&#160;</td><td class="mdescRight">Disallow copying. <br /></td></tr>
<tr class="separator:a2a3c7bb6843b8e1c2cabc9ce5ea2f709"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ae9dd851d38af7c3715a64d0b111ba721"><td class="memItemLeft" align="right" valign="top">size_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae9dd851d38af7c3715a64d0b111ba721">receive_meta_blob_max_size</a> () const</td></tr>
<tr class="memdesc:ae9dd851d38af7c3715a64d0b111ba721"><td class="mdescLeft">&#160;</td><td class="mdescRight">In PEER state: Returns min <code>target_meta_blob.size()</code> such that (1) <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">async_receive_native_handle()</a> shall not fail with <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297ac416e988563e44bf15fc6a81743eef53" title="User called an API with 1 or more arguments against the API spec.">error::Code::S_INVALID_ARGUMENT</a> (only if <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a46b36a6fd79af85829de46b34d3c6849" title="If false then meta_blob.size() &gt; receive_meta_blob_max_size() in PEER-state async_receive_native_hand...">S_META_BLOB_UNDERFLOW_ALLOWED</a> is <code>false</code>; otherwise not relevant), and (2) it shall <em>never</em> fail with <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297adde24987f30a92b953297207ce935210" title="User protocol-code mismatch: local user-provided storage cannot fit entire message received from oppo...">error::Code::S_MESSAGE_SIZE_EXCEEDS_USER_STORAGE</a>.  <a href="classipc_1_1transport_1_1Native__handle__receiver.html#ae9dd851d38af7c3715a64d0b111ba721">More...</a><br /></td></tr>
<tr class="separator:ae9dd851d38af7c3715a64d0b111ba721"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ae4ac1685f00467a6516f9f24f5d8a280"><td class="memTemplParams" colspan="2">template&lt;typename Task_err_sz &gt; </td></tr>
<tr class="memitem:ae4ac1685f00467a6516f9f24f5d8a280"><td class="memTemplItemLeft" align="right" valign="top">bool&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280">async_receive_native_handle</a> (<a class="el" href="namespaceipc_1_1transport.html#a7ee4551983d9df16ec16a3139bac50e8">Native_handle</a> *target_hndl, const <a class="el" href="namespaceipc_1_1util.html#a6cb62ae434900f3a8915b33ec5d61a96">util::Blob_mutable</a> &amp;target_meta_blob, Task_err_sz &amp;&amp;on_done_func)</td></tr>
<tr class="memdesc:ae4ac1685f00467a6516f9f24f5d8a280"><td class="mdescLeft">&#160;</td><td class="mdescRight">In PEER state: Asynchronously awaits one discrete message &ndash; as sent by the opposing peer via <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">Native_handle_sender::send_native_handle()</a> or <code>"Native_handle_sender::*end_sending()"</code> &ndash; and receives it into the given target locations, reliably and in-order.  <a href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280">More...</a><br /></td></tr>
<tr class="separator:ae4ac1685f00467a6516f9f24f5d8a280"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a174ee15818a8bda361bdc40f094faac9"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a174ee15818a8bda361bdc40f094faac9">idle_timer_run</a> (<a class="el" href="namespaceipc_1_1util.html#ac66141280c3b7295a86b65209f31cc58">util::Fine_duration</a> timeout=default_value)</td></tr>
<tr class="memdesc:a174ee15818a8bda361bdc40f094faac9"><td class="mdescLeft">&#160;</td><td class="mdescRight">In PEER state: Irreversibly enables a conceptual idle timer whose potential side effect is, once at least the specified time has passed since the last received low-level traffic (or this call, whichever most recently occurred), to emit the pipe-hosing error <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297aba920b52e9801e4927dd346ad83ce815" title="No messages (optional auto-pings or otherwise) have been received; optionally configured timeout exce...">error::Code::S_RECEIVER_IDLE_TIMEOUT</a>.  <a href="classipc_1_1transport_1_1Native__handle__receiver.html#a174ee15818a8bda361bdc40f094faac9">More...</a><br /></td></tr>
<tr class="separator:a174ee15818a8bda361bdc40f094faac9"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-static-attribs" name="pub-static-attribs"></a>
Static Public Attributes</h2></td></tr>
<tr class="memitem:aa15bb92746ecd8973ed4959ee7606936"><td class="memItemLeft" align="right" valign="top">static const <a class="el" href="namespaceipc_1_1transport.html#a33de1c256addb3964b839dc2dd407d24">Shared_name</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#aa15bb92746ecd8973ed4959ee7606936">S_RESOURCE_TYPE_ID</a></td></tr>
<tr class="memdesc:aa15bb92746ecd8973ed4959ee7606936"><td class="mdescLeft">&#160;</td><td class="mdescRight">Shared_name relative-folder fragment (no separators) identifying this resource type. Equals <code>_sender</code>'s.  <a href="classipc_1_1transport_1_1Native__handle__receiver.html#aa15bb92746ecd8973ed4959ee7606936">More...</a><br /></td></tr>
<tr class="separator:aa15bb92746ecd8973ed4959ee7606936"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a46b36a6fd79af85829de46b34d3c6849"><td class="memItemLeft" align="right" valign="top">static constexpr bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a46b36a6fd79af85829de46b34d3c6849">S_META_BLOB_UNDERFLOW_ALLOWED</a> = value</td></tr>
<tr class="memdesc:a46b36a6fd79af85829de46b34d3c6849"><td class="mdescLeft">&#160;</td><td class="mdescRight">If <code>false</code> then <code>meta_blob.size() &gt; <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae9dd851d38af7c3715a64d0b111ba721" title="In PEER state: Returns min target_meta_blob.size() such that (1) async_receive_native_handle() shall ...">receive_meta_blob_max_size()</a></code> in PEER-state <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">async_receive_native_handle()</a> shall yield non-pipe-hosing error::Code::INVALID_ARGUMENT, and it shall never yield pipe-hosing <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297adde24987f30a92b953297207ce935210" title="User protocol-code mismatch: local user-provided storage cannot fit entire message received from oppo...">error::Code::S_MESSAGE_SIZE_EXCEEDS_USER_STORAGE</a>; else the latter may occur, while the former shall never occur for that reason.  <a href="classipc_1_1transport_1_1Native__handle__receiver.html#a46b36a6fd79af85829de46b34d3c6849">More...</a><br /></td></tr>
<tr class="separator:a46b36a6fd79af85829de46b34d3c6849"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p >A documentation-only <em>concept</em> defining the behavior of an object capable of reliably/in-order <em>receiving</em> of discrete messages, each containing a native handle, a binary blob, or both. </p>
<p >This is paired with the <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a> concept which defines sending of such messages.</p>
<h2>Concept contents </h2>
<p >The concept defines the following behaviors/requirements.</p><ul>
<li>The object has at least 2 states, NULL and PEER. See notes in <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a> w/r/t this; they apply equally here.</li>
<li>The (incoming) transmission-of-messages methods, including reception of graceful-close message and cutting off any further receiving. See their doc headers.</li>
<li>Behavior when the destructor is invoked. See <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae6d2627aa6ee2216cddbc801a28fa268" title="Destroys this peer endpoint which will end the conceptual incoming-direction pipe (in PEER state,...">~Native_handle_receiver()</a> doc header.</li>
<li>Default ctor. See notes in <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a> w/r/t this; they apply equally here.</li>
<li><code><a class="el" href="namespaceipc_1_1transport_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.">sync_io</a></code>-core adopting ctor. Same deal.</li>
<li>Move ctor, move assigment operator. Same deal.</li>
</ul>
<p >The concept (intentionally) does <em>not</em> define the following behaviors:</p><ul>
<li>How to create a <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order receivin...">Native_handle_receiver</a>, except the default, <code><a class="el" href="namespaceipc_1_1transport_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.">sync_io</a></code>-core-adopting, and move ctors. Notes for <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a> apply equally here.</li>
</ul>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="classipc_1_1transport_1_1Native__socket__stream.html" title="Implements both Native_handle_sender and Native_handle_receiver concepts by using a stream-oriented U...">Native_socket_stream</a>: as of this writing one key class that implements this concept (and also <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a>) &ndash; using the Unix domain socket <a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">transport</a>. </dd>
<dd>
<a class="el" href="classipc_1_1transport_1_1Channel.html" title="Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...">Channel</a>, a pipe-composing class template that potentially implements this concept. </dd>
<dd>
<a class="el" href="classipc_1_1transport_1_1Blob__receiver.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order receivin...">Blob_receiver</a>: a degenerate version of the present concept: capable of transmitting only blobs, not <code><a class="el" href="namespaceipc_1_1transport.html#a7ee4551983d9df16ec16a3139bac50e8" title="Convenience alias for the commonly used type util::Native_handle.">Native_handle</a></code>s.</dd></dl>
<h2>Blob underflow semantics </h2>
<p >This potentially important subtlety is regarding the interplay between <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a46b36a6fd79af85829de46b34d3c6849" title="If false then meta_blob.size() &gt; receive_meta_blob_max_size() in PEER-state async_receive_native_hand...">Native_handle_receiver::S_META_BLOB_UNDERFLOW_ALLOWED</a>, <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">async_receive_native_handle()</a> <code>meta_blob.size()</code>, and <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">Native_handle_sender::send_native_handle()</a> <code>meta_blob.size()</code>.</p>
<p >Consider a <code>*this</code> named <code>R</code> and an opposing <code>*_sender</code> named <code>S</code>. Note that <code>R.receive_meta_blob_max_size() == S.send_meta_blob_max_size()</code>; call this limit <code>L</code>. <code>L</code> shall always be in practice small enough to where allocating a buffer of this size as the receive target is reasonable; hence kilobytes at most, not megabytes. (In some cases, such as with <code>Blob_stream_mq_*</code>, it is configurable at runtime. In others, as with <a class="el" href="classipc_1_1transport_1_1Native__socket__stream.html" title="Implements both Native_handle_sender and Native_handle_receiver concepts by using a stream-oriented U...">Native_socket_stream</a>, it is a constant: <a class="el" href="classipc_1_1transport_1_1sync__io_1_1Native__socket__stream.html#a00624e2fc3757012d13e3dc0feb26a21" title="The maximum length of a blob that can be sent by this protocol.">sync_io::Native_socket_stream::S_MAX_META_BLOB_LENGTH</a>.)</p>
<p >As noted in that concept's docs, naturally, <code>S.send_native_handle()</code> shall yield immediate, non-pipe-hosing <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297ac416e988563e44bf15fc6a81743eef53" title="User called an API with 1 or more arguments against the API spec.">error::Code::S_INVALID_ARGUMENT</a>, if <code>meta_blob.size() &gt; L</code>. This is called overflow and is always enforced.</p>
<p >Now consider <code>N = meta_blob.size()</code> for <code>R.async_receive_native_handle()</code>. This is the size of the target blob: how many bytes it <em>can</em> receive. How <code>L</code> is enforced by <code>R</code> is not uniform among this concept's impls: rather it depends on the compile-time constant <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a46b36a6fd79af85829de46b34d3c6849" title="If false then meta_blob.size() &gt; receive_meta_blob_max_size() in PEER-state async_receive_native_hand...">Native_handle_receiver::S_META_BLOB_UNDERFLOW_ALLOWED</a>.</p>
<h3>Semantics: <code>META_BLOB_UNDERFLOW_ALLOWED</code> is <code>false</code></h3>
<p >Suppose it is <code>false</code> (as is the case for <a class="el" href="classipc_1_1transport_1_1Blob__stream__mq__receiver.html" title="Implements Blob_receiver concept by using an adopted Persistent_mq_handle MQ handle to an MQ (message...">Blob_stream_mq_receiver</a>). In that case <code>N &lt; L</code> is <em>disallowed</em>: <code>R.async_receive_native_handle()</code> <em>shall always</em> fail with non-pipe-hosing <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297ac416e988563e44bf15fc6a81743eef53" title="User called an API with 1 or more arguments against the API spec.">error::Code::S_INVALID_ARGUMENT</a> for that reason. Certainly <code>N</code> cannot be zero &ndash; not even if the incoming message is expected to contain only a non-<code>.null() Native_handle</code>.</p>
<dl class="section note"><dt>Note</dt><dd>Formally it's as written. Informally the rationale for allowing this restriction is that some low-level transports have it; and working around it would probably affect performance and is unnatural. In particular <a class="el" href="classipc_1_1transport_1_1Persistent__mq__handle.html#a84f802c77b0ce93d59e7ac78839f14cc" title="Non-blocking receive: pops copy of message from queue into buffer and returns true; if queue is empty...">Persistent_mq_handle::try_receive()</a> (MQ receive) shall immediately fail if a target buffer is supplied smaller than <a class="el" href="classipc_1_1transport_1_1Persistent__mq__handle.html#ae2efe92707c53c46bc70b84f96bda217" title="Returns the max message size of the underlying queue.">Persistent_mq_handle::max_msg_size()</a>. For both POSIX (<code>man mq_receive</code>) and bipc (<code>boost::interprocess::message_queue::try_receive()</code> docs and source code) it is disallowed at the low-level API level.</dd></dl>
<p>Thus since <code>N &gt;= L</code> is guaranteed before any actual receipt attempt is made, it is <em>impossible</em> for a message to arrive such that its meta-blob's size would overflow the target blob (buffer) (of size <code>N</code>). Therefore <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297adde24987f30a92b953297207ce935210" title="User protocol-code mismatch: local user-provided storage cannot fit entire message received from oppo...">error::Code::S_MESSAGE_SIZE_EXCEEDS_USER_STORAGE</a> shall not be emitted.</p>
<h3>Semantics: <code>META_BLOB_UNDERFLOW_ALLOWED</code> is <code>true</code></h3>
<p >Suppose it is <code>true</code> (as is the case for <a class="el" href="classipc_1_1transport_1_1Native__socket__stream.html" title="Implements both Native_handle_sender and Native_handle_receiver concepts by using a stream-oriented U...">Native_socket_stream</a>). In that case <code>N &lt; L</code> is allowed, in the sense that <code>R.async_receive_native_handle()</code> <em>shall not</em> fail with non-pipe-hosing <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297ac416e988563e44bf15fc6a81743eef53" title="User called an API with 1 or more arguments against the API spec.">error::Code::S_INVALID_ARGUMENT</a> for that reason. In particular, in that case, <code>N</code> can even be zero: this implies the incoming message <em>must</em> contain a non-<code>.null() Native_handle</code> (it is not allowed to send a message with no content at all). (In the case of degenerate concept <a class="el" href="classipc_1_1transport_1_1Blob__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Blob_sender</a>, <code>N</code> must exceed zero, as it cannot transmit anything but blobs.)</p>
<p >However suppose a message has arrived, and its meta-blob's size &ndash; which cannot exceed <code>L</code> &ndash; is larger than <code>N</code>. I.e., it would <em>underflow</em> the user-supplied target buffer (blob). In that case:</p><ul>
<li><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">async_receive_native_handle()</a> shall emit <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297adde24987f30a92b953297207ce935210" title="User protocol-code mismatch: local user-provided storage cannot fit entire message received from oppo...">error::Code::S_MESSAGE_SIZE_EXCEEDS_USER_STORAGE</a>.</li>
<li>This error shall be pipe-hosing (further receive attempts will yield the same error).</li>
</ul>
<p >Informal tips: Any blob-size error can be completely avoided by always supplying target blob with <code>N == L</code>. (<code>N &gt; L</code> will also work but may be considered wasteful, all else being equal.) In addition this tactic will ensure the code will generically work with a different <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order receivin...">Native_handle_receiver</a> impl for which <code>S_META_BLOB_UNDERFLOW_ALLOWED == false</code>. Alternatively, the user protocol may be such that you simply know that <code>S</code> will never send messages beyond some limit (smaller than <code>L</code>), perhaps for particular messages. In that case <code>N</code> can be set to this smaller-than-<code>L</code> value. However &ndash; such code will fail if the concept impl is later to switched to one with <code>S_META_BLOB_UNDERFLOW_ALLOWED == true</code>. This may or may not be an issue depending on your future dev plans.</p>
<h3>Summary</h3>
<p >This dichotomy of possible semantics is a conscious choice. Mode <code>false</code> is a necessity: some low-level transports enforce it, period. Mode <code>true</code> is to support a possible algorithmic desire to allocate smaller-than-<code>L</code> target buffers. The problem is some low-level transports allow this; but others don't. We did not want to impose one type's limitations on users of the other type. Therefore, if your code is agnostic to the type of transport, then code as-if <code>S_META_BLOB_UNDERFLOW_ALLOWED == false</code>. Otherwise you may code otherwise.</p>
<h2>Rationale: Why no <code>end_receiving()</code>, given opposing concept has <code>*end_sending()</code>? </h2>
<p >An early version of <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order receivin...">Native_handle_receiver</a> and <a class="el" href="classipc_1_1transport_1_1Blob__receiver.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order receivin...">Blob_receiver</a> did have an <code>end_receiving()</code>. The idea was it would have 2 effects (plus 1 bonus):</p><ol type="1">
<li>Any ongoing <code>async_receive_*()</code>s would be interrupted with in-pipe-hosing error <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297aad44f87d53255ba573d57086dfeab805" title="Will not receive message: either opposing user sent graceful-close via API.">error::Code::S_RECEIVES_FINISHED_CANNOT_RECEIVE</a> &ndash; the same one as when receing a graceful-close from opposing <code>*end_sending()</code>.</li>
<li>There would be no further reading from the low-level transport for any reason.</li>
<li>There was also the <em>thought</em>, but not the action, that an impl could inform the <em>opposing sender</em> of the pipe being closed by the reader. This would be conceptually similar to SIGPIPE in POSIX. In practice, of the available low-level transports as of this writing, only <a class="el" href="classipc_1_1transport_1_1Native__socket__stream.html" title="Implements both Native_handle_sender and Native_handle_receiver concepts by using a stream-oriented U...">Native_socket_stream</a> could actually implement it, as the otherwise-full-duplex independent pipes do live in this same peer (Unix domain socket), so the out-pipe could be used to inform the other guy that <em>his</em> out-pipe (our in-pipe) is now pointless. <code>Blob_stream_mq_*</code> are fully independent, operating on separate MQ kernel objects, so it was not realistically possible in that case.</li>
</ol>
<p >In order: (1) is fairly dubious: the local user should know when they've stopped receiving and don't need to use this mechanism to inform themselves. (3), as stated, sounded like a possible future improvement, but time told us it was not going to work out: if only a 2-pipe transport can do it in any case, organizing a concept around such a thing is just complicated. If necessary the user can (and we think likely will) just arrange their own protocol. So that leaves (2).</p>
<p >To begin with &ndash; in reality user protocols tend to be designed to not need such measures. If the reader is no longer interested, writer will probably know that. This is not networking after all: it is IPC. That aside, though, it only makes sense in any case if an impl <em>chooses</em> to greedily cache all low-level in-traffic in user RAM, even while no <code>async_receive_*()</code>s are pending to read it. Early on we actually did do that; but with the move to <code><a class="el" href="namespaceipc_1_1transport_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.">sync_io</a></code>-pattern cores, and after contemplating "Rationale: Why is send-native-handle not asynchronous?" (<a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a> concept doc header), we got rid of this waste of compute, letting unwanted in-traffic accumulate within a sender peer object (<a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a>, <a class="el" href="classipc_1_1transport_1_1Blob__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Blob_sender</a>) only. So in practice:</p>
<p >If <code>end_receiving()</code> does not signal anything of value ((1) and (3)), and does not actually prevent any low-level reading that would otherwise occur, then it is a pointless complication. So that is why we got rid of it. </p>

<p class="definition">Definition at line <a class="el" href="native__handle__transport_8hpp_source.html#l00603">603</a> of file <a class="el" href="native__handle__transport_8hpp_source.html">native_handle_transport.hpp</a>.</p>
</div><h2 class="groupheader">Constructor &amp; Destructor Documentation</h2>
<a id="a748df49e5098e922c5974643d7a1bbde" name="a748df49e5098e922c5974643d7a1bbde"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a748df49e5098e922c5974643d7a1bbde">&#9670;&nbsp;</a></span>Native_handle_receiver() <span class="overload">[1/3]</span></h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">ipc::transport::Native_handle_receiver::Native_handle_receiver </td>
          <td>(</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Default ctor: Creates a peer object in NULL (neither connected nor connecting) state. </p>
<p >In this state, all transmission-related methods (e.g., <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">async_receive_native_handle()</a>) shall return <code>false</code> and otherwise no-op (aside from possible logging).</p>
<p >All notes from Native_handle_sender() default ctor doc header apply here analogously. They are helpful so please read Native_handle_sender() doc header. </p>

</div>
</div>
<a id="accd891967ffb57341a26ed0764012713" name="accd891967ffb57341a26ed0764012713"></a>
<h2 class="memtitle"><span class="permalink"><a href="#accd891967ffb57341a26ed0764012713">&#9670;&nbsp;</a></span>Native_handle_receiver() <span class="overload">[2/3]</span></h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">ipc::transport::Native_handle_receiver::Native_handle_receiver </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="classipc_1_1transport_1_1sync__io_1_1Native__handle__receiver.html">sync_io::Native_handle_receiver</a> &amp;&amp;&#160;</td>
          <td class="paramname"><em>sync_io_core_in_peer_state_moved</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p><code><a class="el" href="namespaceipc_1_1transport_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.">sync_io</a></code>-core-adopting ctor: Creates a peer object in PEER state by subsuming a <code><a class="el" href="namespaceipc_1_1transport_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.">sync_io</a></code> core in that state. </p>
<p >That core must be as-if-just-cted (having performed no work and not been configured via <code>.start_*_ops()</code>). That core object becomes as-if default-cted (therefore in NULL state).</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">sync_io_core_in_peer_state_moved</td><td>See above. </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="a01de65ed1a7c747e5569e14221b6f9bf" name="a01de65ed1a7c747e5569e14221b6f9bf"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a01de65ed1a7c747e5569e14221b6f9bf">&#9670;&nbsp;</a></span>Native_handle_receiver() <span class="overload">[3/3]</span></h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">ipc::transport::Native_handle_receiver::Native_handle_receiver </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html">Native_handle_receiver</a> &amp;&amp;&#160;</td>
          <td class="paramname"><em>src</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Move-constructs from <code>src</code>; <code>src</code> becomes as-if default-cted (therefore in NULL state). </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">src</td><td>Source object. For reasonable uses of <code>src</code> after this ctor returns: see default ctor doc header. </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="ae6d2627aa6ee2216cddbc801a28fa268" name="ae6d2627aa6ee2216cddbc801a28fa268"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ae6d2627aa6ee2216cddbc801a28fa268">&#9670;&nbsp;</a></span>~Native_handle_receiver()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">ipc::transport::Native_handle_receiver::~Native_handle_receiver </td>
          <td>(</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Destroys this peer endpoint which will end the conceptual incoming-direction pipe (in PEER state, and if it's still active) and cancels any pending completion handlers by invoking them ASAP with <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297afe29343445a7bf167cc186a44bd2c6ed" title="Async completion handler is being called prematurely, because underlying object is shutting down,...">error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER</a>. </p>
<p >As of this writing these are the completion handlers that would therefore be called:</p><ul>
<li>Any handler passed to <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">async_receive_native_handle()</a> that has not yet been invoked. There can be 0 or more of these.</li>
</ul>
<p >The pending completion handler(s) (if any) will be called from an unspecified thread that is not the calling thread. Any associated captured state for that handler will be freed shortly after the handler returns.</p>
<p >The rest of the notes in ~Native_handle_sender() apply equally here.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#aa2354a74bc6cdff9389d0b7b642fbadd" title="Destroys this peer endpoint which will end the conceptual outgoing-direction pipe (in PEER state,...">Native_handle_sender::~Native_handle_sender()</a>: sister concept with essentially equal requirements. </dd>
<dd>
<a class="el" href="classipc_1_1transport_1_1Native__socket__stream.html#a1ff9e6811c0d662a6a960602be5926e0" title="Implements Native_handle_sender and Native_handle_receiver APIs at the same time, per their concept c...">Native_socket_stream::~Native_socket_stream()</a>: implements concept (also implements just-mentioned sister concept). </dd></dl>

</div>
</div>
<h2 class="groupheader">Member Function Documentation</h2>
<a id="ae4ac1685f00467a6516f9f24f5d8a280" name="ae4ac1685f00467a6516f9f24f5d8a280"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ae4ac1685f00467a6516f9f24f5d8a280">&#9670;&nbsp;</a></span>async_receive_native_handle()</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Task_err_sz &gt; </div>
      <table class="memname">
        <tr>
          <td class="memname">bool ipc::transport::Native_handle_receiver::async_receive_native_handle </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="namespaceipc_1_1transport.html#a7ee4551983d9df16ec16a3139bac50e8">Native_handle</a> *&#160;</td>
          <td class="paramname"><em>target_hndl</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const <a class="el" href="namespaceipc_1_1util.html#a6cb62ae434900f3a8915b33ec5d61a96">util::Blob_mutable</a> &amp;&#160;</td>
          <td class="paramname"><em>target_meta_blob</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">Task_err_sz &amp;&amp;&#160;</td>
          <td class="paramname"><em>on_done_func</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>In PEER state: Asynchronously awaits one discrete message &ndash; as sent by the opposing peer via <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">Native_handle_sender::send_native_handle()</a> or <code>"Native_handle_sender::*end_sending()"</code> &ndash; and receives it into the given target locations, reliably and in-order. </p>
<p >The message is, therefore, one of the following:</p><ul>
<li>A binary blob; a native handle; or both. This is indicated by <code>on_done_func(Error_code(), N)</code>. The falsy code indicates success; <code>N &lt;= target_meta_blob.size()</code> indicates the number of bytes received into <code>target_meta_blob.data()</code> (zero means no blob was sent in the message). <code>*target_hndl</code> is set (<code>target_hndl-&gt;null() == true</code> means no handle was sent in the message).</li>
<li>Graceful-close. This is indicated by <code>on_done_func(error::code::S_RECEIVES_FINISHED_CANNOT_RECEIVE, 0)</code>; neither the target blob nor target native handle are touched.</li>
</ul>
<p >If <code>*this</code> is not in PEER state (in particular if it is default-cted or moved-from), returns <code>false</code> immediately instead and otherwise no-ops (logging aside).</p>
<h3>Blob copying behavior; synchronicity/blockingness guarantees</h3>
<p ><code>*target_hndl</code> and the area described by <code>target_meta_blob</code> must both remain valid until <code>on_done_func()</code> executes. The method itself shall be non-blocking.</p>
<p >The implementation shall, informally, strive to <em>not</em> copy the received blob (if any) into <code>target_meta_blob.data()...</code> except from the low-level transport mechanism. That is: it shall strive to not store the blob data in some internal buffer before ending up in <code>target_meta_blob.data()...</code>.</p>
<h3>Error semantics</h3>
<p >An <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89" title="Short-hand for flow::Error_code which is very common.">Error_code</a> is generated and passed as the 1st arg to <code>on_done_func()</code>. A falsy one indicates success. A truthy one indicates failure; but in particular:</p><ul>
<li><a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297afe29343445a7bf167cc186a44bd2c6ed" title="Async completion handler is being called prematurely, because underlying object is shutting down,...">error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER</a> (destructor called, canceling all pending ops; spiritually identical to <code>boost::asio::error::operation_aborted</code>);</li>
<li>only if <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a46b36a6fd79af85829de46b34d3c6849" title="If false then meta_blob.size() &gt; receive_meta_blob_max_size() in PEER-state async_receive_native_hand...">S_META_BLOB_UNDERFLOW_ALLOWED</a> is <code>true</code>:<ul>
<li><a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297adde24987f30a92b953297207ce935210" title="User protocol-code mismatch: local user-provided storage cannot fit entire message received from oppo...">error::Code::S_MESSAGE_SIZE_EXCEEDS_USER_STORAGE</a> (opposing peer has sent a message with a meta-blob exceeding <code>target_meta_blob.size()</code> in length; in particular one can give an empty buffer if no meta-blob expected);</li>
</ul>
</li>
<li><a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297aad44f87d53255ba573d57086dfeab805" title="Will not receive message: either opposing user sent graceful-close via API.">error::Code::S_RECEIVES_FINISHED_CANNOT_RECEIVE</a> (peer gracefully closed pipe via <code>*end_sending()</code>);</li>
<li><a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297aba920b52e9801e4927dd346ad83ce815" title="No messages (optional auto-pings or otherwise) have been received; optionally configured timeout exce...">error::Code::S_RECEIVER_IDLE_TIMEOUT</a> (idle timeout: see <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a174ee15818a8bda361bdc40f094faac9" title="In PEER state: Irreversibly enables a conceptual idle timer whose potential side effect is,...">idle_timer_run()</a>);</li>
<li>other arbitrary codes are possible.</li>
<li>No would-block-like error condition shall be emitted.</li>
</ul>
<p >A non-success on-done invocation means the incoming pipe is hosed. (It is recommended they cease to use the pipe and invoke the destructor to free resources.) If such a non-success code is emitted, the same one shall be emitted by all further <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">async_receive_native_handle()</a> calls on <code>*this</code>. Key exception:</p><ul>
<li><a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297ac416e988563e44bf15fc6a81743eef53" title="User called an API with 1 or more arguments against the API spec.">error::Code::S_INVALID_ARGUMENT</a>:<ul>
<li>This refers to an invalid argument to <em>this</em> method invocation.<ul>
<li>If and only if <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a46b36a6fd79af85829de46b34d3c6849" title="If false then meta_blob.size() &gt; receive_meta_blob_max_size() in PEER-state async_receive_native_hand...">S_META_BLOB_UNDERFLOW_ALLOWED</a> is <code>false</code>: A length floor on the target blob is imposed. Hence if <code>target_meta_blob.size() &lt; <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae9dd851d38af7c3715a64d0b111ba721" title="In PEER state: Returns min target_meta_blob.size() such that (1) async_receive_native_handle() shall ...">receive_meta_blob_max_size()</a></code> then <code>S_INVALID_ARGUMENT</code> is emitted.</li>
</ul>
</li>
<li>This shall <em>not</em> hose the pipe. Subsequent async-receives may be attempted with reasonable hope of success.</li>
<li>At the impl's discretion, other conditions <em>may</em> lead to <code>S_INVALID_ARGUMENT</code>. If so they must be documented.</li>
</ul>
</li>
</ul>
<h3>Thread safety</h3>
<p >You may call this either from any thread including the unspecified thread running within another call's <code>on_done_func()</code>. It is <em>not</em> required to be safe to call concurrently with any <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order receivin...">Native_handle_receiver</a> API, including this one and the destructor, invoked on <code>*this</code>.</p>
<dl class="tparams"><dt>Template Parameters</dt><dd>
  <table class="tparams">
    <tr><td class="paramname">Task_err_sz</td><td>A functor type with signature identical to <code>flow::async::Task_asio_err_sz</code>. </td></tr>
  </table>
  </dd>
</dl>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">target_hndl</td><td><code>*target_hndl</code> shall be set by the time <code>on_done_func()</code> is executed with a falsy code. See above. </td></tr>
    <tr><td class="paramname">target_meta_blob</td><td><code>target_meta_blob.data()...</code> shall be written to by the time <code>on_done_func()</code> is executed with a falsy code, bytes numbering <code>N</code>, where <code>N</code> is passed to that callback. <code>N</code> shall not exceed <code>target_meta_blob.size()</code>. See above. </td></tr>
    <tr><td class="paramname">on_done_func</td><td>See above. This shall be invoked from an unspecified thread that is not the calling thread. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><code>false</code> if <code>*this</code> is not in PEER (connected, transmitting) state; otherwise <code>true</code>. </dd></dl>

</div>
</div>
<a id="a174ee15818a8bda361bdc40f094faac9" name="a174ee15818a8bda361bdc40f094faac9"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a174ee15818a8bda361bdc40f094faac9">&#9670;&nbsp;</a></span>idle_timer_run()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">bool ipc::transport::Native_handle_receiver::idle_timer_run </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="namespaceipc_1_1util.html#ac66141280c3b7295a86b65209f31cc58">util::Fine_duration</a>&#160;</td>
          <td class="paramname"><em>timeout</em> = <code>default_value</code></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>In PEER state: Irreversibly enables a conceptual idle timer whose potential side effect is, once at least the specified time has passed since the last received low-level traffic (or this call, whichever most recently occurred), to emit the pipe-hosing error <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297aba920b52e9801e4927dd346ad83ce815" title="No messages (optional auto-pings or otherwise) have been received; optionally configured timeout exce...">error::Code::S_RECEIVER_IDLE_TIMEOUT</a>. </p>
<p >The implementation shall guarantee the observer idle timeout is at least the provided value but may exceed this value for internal reasons, as long as it's by a less than human-perceptible period (roughly speaking &ndash; milliseconds, not seconds).</p>
<p >If <code>*this</code> is not in PEER state (in particular if it is default-cted or moved-from), returns <code>false</code> immediately instead and otherwise no-ops (logging aside). If <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a174ee15818a8bda361bdc40f094faac9" title="In PEER state: Irreversibly enables a conceptual idle timer whose potential side effect is,...">idle_timer_run()</a> has already been called successfuly, subsequently it will return <code>false</code> and no-op (logging aside).</p>
<h3>Important: Relationship between <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a174ee15818a8bda361bdc40f094faac9" title="In PEER state: Irreversibly enables a conceptual idle timer whose potential side effect is,...">idle_timer_run()</a> and <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">async_receive_native_handle()</a></h3>
<p ><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a174ee15818a8bda361bdc40f094faac9" title="In PEER state: Irreversibly enables a conceptual idle timer whose potential side effect is,...">idle_timer_run()</a> is optional: if you have not called it, then the following does not apply. If you <em>have</em> called it:</p>
<p >It will work usefully if and only if subsequently an <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">async_receive_native_handle()</a> is oustanding at least once each <code>timeout</code>. Informally this means it's best to immediately issue <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">async_receive_native_handle()</a> &ndash; unless one is already oustanding &ndash; and then as soon as that completes (sans error) issue at least one more; and so on. Why? What are we talking about? Simple: <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">async_receive_native_handle()</a> impl is <em>not</em> required to read any more data from the low-level transport than is sufficient to satisfy the current <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">async_receive_native_handle()</a> deficit. (If it were required to do so, it would've been required to store copies of incoming meta-blobs when there's no user-request deficit; we've consciously avoided unnecessary copying.) So while there's no <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">async_receive_native_handle()</a> outstanding, <code>*this</code> will be considered idle; and once that continues long enough for <code>timeout</code> to be exceeded, the idle timer will hose the in-pipe.</p>
<p >So: If you plan to use <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a174ee15818a8bda361bdc40f094faac9" title="In PEER state: Irreversibly enables a conceptual idle timer whose potential side effect is,...">idle_timer_run()</a>, then you need to be ~always async-receiving. Otherwise you'll risk hitting idle-timeout, even as the other side diligently sends stuff (<code>auto_ping()</code> or otherwise).</p>
<h3>Error semantics</h3>
<p >If and only if the timeout does occur down the line, the aforementioned error will be emitted via <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">async_receive_native_handle()</a> (or similar) handler. It shall be treated as the reason to hose the pipe (assuming it was not hosed by something else earlier).</p>
<h3>Thread safety</h3>
<p >You may call this either from any thread including the unspecified thread running within another call's <code>on_done_func()</code>. It is <em>not</em> required to be safe to call concurrently with any API, including this one and the destructor, invoked on <code>*this</code>.</p>
<h3>Suggested use</h3>
<p >Informally: There are roughly two approaches to using <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a174ee15818a8bda361bdc40f094faac9" title="In PEER state: Irreversibly enables a conceptual idle timer whose potential side effect is,...">idle_timer_run()</a>.</p>
<p >Firstly it can be used to gauge the state of the opposing process; if no auto-pings are arriving regularly, then the opposing <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a> (or similar) must be zombified or overloaded. To use it in this capacity, typically one must use <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a8a2f1282c18faec36aabf29c99b87054" title="In PEER state: Irreversibly enables periodic auto-pinging of opposing receiver with low-level message...">Native_handle_sender::auto_ping()</a> (or similar) on the opposing side. Typically one would then leave <code>timeout</code> at its suggested default value.</p>
<p >Secondly it can be used to more generally ensure some application algorithm on the opposing side (presumably cooperating with the algorithm on the local side) is sending messages with expected frequency. That is, one would not use <code>auto_ping()</code> but rather send their own messages in a way that makes sense for the applications' algorithm.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">timeout</td><td>The idle timeout to observe. The optional default is chosen by the impl to most reasonably work with the opposing <code>auto_ping()</code> to detect a zombified/overloaded peer. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><code>false</code> if <code>*this</code> is not in PEER (connected, transmitting) state, or if already called successfully in <code>PEER</code> state; otherwise <code>true</code>. </dd></dl>

</div>
</div>
<a id="a78fbe1f543021b7b5d2ec1be70b83660" name="a78fbe1f543021b7b5d2ec1be70b83660"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a78fbe1f543021b7b5d2ec1be70b83660">&#9670;&nbsp;</a></span>operator=()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html">Native_handle_receiver</a> &amp; ipc::transport::Native_handle_receiver::operator= </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html">Native_handle_receiver</a> &amp;&amp;&#160;</td>
          <td class="paramname"><em>src</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Move-assigns from <code>src</code>; <code>*this</code> acts as if destructed; <code>src</code> becomes as-if default-cted (therefore in NULL state). </p>
<p >No-op if <code>&amp;src == this</code>.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae6d2627aa6ee2216cddbc801a28fa268" title="Destroys this peer endpoint which will end the conceptual incoming-direction pipe (in PEER state,...">~Native_handle_receiver()</a>.</dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">src</td><td>Source object. For reasonable uses of <code>src</code> after this ctor returns: see default ctor doc header. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><code>*this</code>. </dd></dl>

</div>
</div>
<a id="ae9dd851d38af7c3715a64d0b111ba721" name="ae9dd851d38af7c3715a64d0b111ba721"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ae9dd851d38af7c3715a64d0b111ba721">&#9670;&nbsp;</a></span>receive_meta_blob_max_size()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">size_t ipc::transport::Native_handle_receiver::receive_meta_blob_max_size </td>
          <td>(</td>
          <td class="paramname"></td><td>)</td>
          <td> const</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>In PEER state: Returns min <code>target_meta_blob.size()</code> such that (1) <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">async_receive_native_handle()</a> shall not fail with <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297ac416e988563e44bf15fc6a81743eef53" title="User called an API with 1 or more arguments against the API spec.">error::Code::S_INVALID_ARGUMENT</a> (only if <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a46b36a6fd79af85829de46b34d3c6849" title="If false then meta_blob.size() &gt; receive_meta_blob_max_size() in PEER-state async_receive_native_hand...">S_META_BLOB_UNDERFLOW_ALLOWED</a> is <code>false</code>; otherwise not relevant), and (2) it shall <em>never</em> fail with <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297adde24987f30a92b953297207ce935210" title="User protocol-code mismatch: local user-provided storage cannot fit entire message received from oppo...">error::Code::S_MESSAGE_SIZE_EXCEEDS_USER_STORAGE</a>. </p>
<p >Please see "Blob underflow semantics" for explanation of these semantics.</p>
<p >Always the same value once in PEER state. The opposing Blob_sender::send_meta_blob_max_size() shall return the same value (in the opposing object potentially in a different process).</p>
<p >If <code>*this</code> is not in PEER state (in particular if it is default-cted or moved-from), returns zero; else a positive value.</p>
<dl class="section return"><dt>Returns</dt><dd>See above. </dd></dl>

</div>
</div>
<h2 class="groupheader">Member Data Documentation</h2>
<a id="a46b36a6fd79af85829de46b34d3c6849" name="a46b36a6fd79af85829de46b34d3c6849"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a46b36a6fd79af85829de46b34d3c6849">&#9670;&nbsp;</a></span>S_META_BLOB_UNDERFLOW_ALLOWED</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">constexpr bool ipc::transport::Native_handle_receiver::S_META_BLOB_UNDERFLOW_ALLOWED = value</td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">static</span><span class="mlabel">constexpr</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>If <code>false</code> then <code>meta_blob.size() &gt; <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae9dd851d38af7c3715a64d0b111ba721" title="In PEER state: Returns min target_meta_blob.size() such that (1) async_receive_native_handle() shall ...">receive_meta_blob_max_size()</a></code> in PEER-state <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">async_receive_native_handle()</a> shall yield non-pipe-hosing error::Code::INVALID_ARGUMENT, and it shall never yield pipe-hosing <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297adde24987f30a92b953297207ce935210" title="User protocol-code mismatch: local user-provided storage cannot fit entire message received from oppo...">error::Code::S_MESSAGE_SIZE_EXCEEDS_USER_STORAGE</a>; else the latter may occur, while the former shall never occur for that reason. </p>
<dl class="section see"><dt>See also</dt><dd>"Blob underflow semantics" in class concept doc header. </dd></dl>

<p class="definition">Definition at line <a class="el" href="native__handle__transport_8hpp_source.html#l00619">619</a> of file <a class="el" href="native__handle__transport_8hpp_source.html">native_handle_transport.hpp</a>.</p>

</div>
</div>
<a id="aa15bb92746ecd8973ed4959ee7606936" name="aa15bb92746ecd8973ed4959ee7606936"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aa15bb92746ecd8973ed4959ee7606936">&#9670;&nbsp;</a></span>S_RESOURCE_TYPE_ID</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">const <a class="el" href="namespaceipc_1_1transport.html#a33de1c256addb3964b839dc2dd407d24">Shared_name</a> ipc::transport::Native_handle_receiver::S_RESOURCE_TYPE_ID</td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">static</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Shared_name relative-folder fragment (no separators) identifying this resource type. Equals <code>_sender</code>'s. </p>

<p class="definition">Definition at line <a class="el" href="native__handle__transport_8hpp_source.html#l00609">609</a> of file <a class="el" href="native__handle__transport_8hpp_source.html">native_handle_transport.hpp</a>.</p>

</div>
</div>
<hr/>The documentation for this class was generated from the following file:<ul>
<li>transport/<a class="el" href="native__handle__transport_8hpp_source.html">native_handle_transport.hpp</a></li>
</ul>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Thu May 2 2024 23:56:39 for Flow-IPC by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.4
</small></address>
</body>
</html>
